Skip to content

feat(mcp-gateway): scaffold runtime worker#3697

Open
pandemicsyn wants to merge 2 commits into
mainfrom
feat/mcp-gateway-scaffold
Open

feat(mcp-gateway): scaffold runtime worker#3697
pandemicsyn wants to merge 2 commits into
mainfrom
feat/mcp-gateway-scaffold

Conversation

@pandemicsyn
Copy link
Copy Markdown
Contributor

Summary

  • Add the initial services/mcp-gateway Worker scaffold for the app-owned control plane / Worker-owned runtime architecture, including top-level production Wrangler config, env.dev, Hyperdrive, per-instance DO binding, Analytics Engine binding, generated Worker types, and local service docs.
  • Add a route-only Hono entrypoint and route-shape tests for /health, scoped /mcp-connect/... runtime routes, and generic/scoped protected-resource metadata routes; all gateway runtime routes remain 501 stubs so the service is safe to merge before OAuth/runtime implementation.
  • Keep the gateway architecture notes in the planning workspace until PR2 to avoid introducing a partially overlapping spec surface in the repo before the functional implementation lands.

Verification

  • Started pnpm --filter cloudflare-mcp-gateway dev and confirmed the local Worker booted on http://0.0.0.0:8806.
  • Requested GET /health locally and confirmed 200 with {"status":"ok","service":"mcp-gateway"}.
  • Requested GET /mcp-connect/user/user-123/config-123/route-123 locally and confirmed 501 with {"status":"not_implemented"}.
  • Additional manual verification details:

Visual Changes

N/A

Reviewer Notes

  • PR1 intentionally does not attach mcp.kilo.ai or implement OAuth, gateway tables/migrations, provider discovery, proxying, or DO domain behavior.
  • The Worker uses a top-level production Wrangler config plus env.dev; the compatibility date is pinned to 2026-05-15 because that was the newest date supported by the local Wrangler runtime used during validation.
  • The branch contains two commits: the scaffold and a follow-up that defers the copied gateway specs to PR2.

import { notImplementedResponse } from '../lib/responses';

export function handleUserConnect(c: Context<MCPGatewayEnv>, params: UserConnectRouteParams) {
UserConnectRouteParamsSchema.parse(params);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: Zod parse result is discarded — use the validated value

The result of UserConnectRouteParamsSchema.parse(params) is thrown away and the original params argument (which TypeScript accepts as UserConnectRouteParams but has not actually been validated at the call site — the caller passes c.req.param() which is Record<string, string>) is used implicitly by the stub response. This is currently harmless because the handler only calls notImplementedResponse, but as soon as real logic is added the handler will operate on the raw Hono path params rather than the Zod-validated and potentially-transformed object. It is also inconsistent with the IO-boundary convention documented in AGENTS.md.

Suggest:

const validatedParams = UserConnectRouteParamsSchema.parse(params);
// use validatedParams going forward

Same pattern applies to handleOrgConnect on line 17.

c: Context<MCPGatewayEnv>,
params: UserConnectRouteParams
) {
UserConnectRouteParamsSchema.parse(params);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: Zod parse result is discarded — use the validated value

Same issue as connect.handler.ts:12: UserConnectRouteParamsSchema.parse(params) validates but the returned object is ignored. Use the return value when real logic is added so Zod transforms/coercions are not silently bypassed. Same applies to OrgConnectRouteParamsSchema.parse(params) on line 27.

@kilo-code-bot
Copy link
Copy Markdown
Contributor

kilo-code-bot Bot commented Jun 3, 2026

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

Discarded Zod parse return values in all four route handlers will silently bypass Zod transforms once real business logic is added, violating the IO-boundary contract in AGENTS.md.

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 0
Issue Details (click to expand)

WARNING

File Line Issue
services/mcp-gateway/src/handlers/connect.handler.ts 12 UserConnectRouteParamsSchema.parse(params) result discarded; handler operates on raw Hono path params. Same for handleOrgConnect line 17.
services/mcp-gateway/src/handlers/protected-resource.handler.ts 19 UserConnectRouteParamsSchema.parse(params) result discarded. Same for OrgConnectRouteParamsSchema.parse line 27.
Other Observations (not in diff)

Wildcard route params include a "*" key: Routes like /mcp-connect/user/:userId/:configId/:routeKey/* produce c.req.param() objects containing an extra "*" key (the matched wildcard segment). Zod's z.object() strips unknown keys by default, so the wildcard portion is silently discarded. This is harmless in PR1, but the intent should be documented — future handlers that need the sub-path (e.g. to proxy /tools/list downstream) must extract the * param explicitly before parsing with the schema.

dev environment duplicates production bindings verbatim in wrangler.jsonc: The env.dev block repeats durable_objects, hyperdrive, and analytics_engine_datasets identically to the top-level config. Wrangler env blocks do not inherit bindings from the top level, so duplication is required by the platform — no action needed, just noting it for reviewers unfamiliar with Wrangler's env semantics.

Files Reviewed (11 files)
  • pnpm-lock.yaml
  • services/mcp-gateway/.dev.vars.example
  • services/mcp-gateway/AGENTS.md
  • services/mcp-gateway/README.md
  • services/mcp-gateway/package.json
  • services/mcp-gateway/src/durable-objects/MCPGatewayInstance.do.ts
  • services/mcp-gateway/src/handlers/connect.handler.ts — 2 issues
  • services/mcp-gateway/src/handlers/health.handler.ts
  • services/mcp-gateway/src/handlers/protected-resource.handler.ts — 2 issues
  • services/mcp-gateway/src/lib/responses.ts
  • services/mcp-gateway/src/mcp-gateway.worker.test.ts
  • services/mcp-gateway/src/mcp-gateway.worker.ts
  • services/mcp-gateway/src/schemas/routes.schema.ts
  • services/mcp-gateway/src/types.ts
  • services/mcp-gateway/tsconfig.json
  • services/mcp-gateway/vitest.config.ts
  • services/mcp-gateway/worker-configuration.d.ts
  • services/mcp-gateway/wrangler.jsonc

Fix these issues in Kilo Cloud


Reviewed by claude-sonnet-4.6 · 888,341 tokens

Review guidance: REVIEW.md from base branch main

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant